Summary

Adds ESEARCH support to ImapFlow's search() method, enabling efficient search result handling for large mailboxes.

• Handles COUNT, MIN, MAX, ALL, and PARTIAL result keywords from * ESEARCH untagged responses
• Emits UID SEARCH RETURN (COUNT PARTIAL 1:100 ...) when returnOptions is passed and the server advertises ESEARCH capability
• Callers without returnOptions get the same number[] result as before
• Graceful fallback — derives ESearchResult client-side from the plain number[] (COUNT from .length, MIN/MAX from sorted ends, ALL via packMessageRange) when the server lacks ESEARCH

New API

// Existing call — unchanged, returns number[]
const uids = await client.search({ seen: false }, { uid: true });

// New: ESEARCH with returnOptions — returns ESearchResult
const result = await client.search({ seen: false }, {
  uid: true,
  returnOptions: ['COUNT', 'MIN', 'MAX', 'ALL']
});
// result = { count: 1847, min: 1001, max: 87432, all: '1001,1005:1010,...' }

// New: Paged search via RFC 9394 PARTIAL
const page = await client.search({ before: new Date('2022-01-01') }, {
  uid: true,
  returnOptions: ['COUNT', { partial: '1:100' }]
});
// page = { count: 34201, partial: { range: '1:100', messages: '2001,2003:2020,...' } }

Motivation

For large mailboxes (70k+ messages), client.search() currently returns every matching UID as a number[], which is expensive to transfer and parse. ESEARCH allows:

• COUNT only — single integer instead of full UID list (O(1) vs O(n) on the wire)
• MIN/MAX — boundary UIDs without materializing the full set
• ALL as compact sequence-set — "1,5:10,20" instead of space-separated individual UIDs
• PARTIAL (RFC 9394) — server-side paged results

Implementation notes

• Capability check: ESEARCH RETURN clause is only emitted when connection.capabilities.has('ESEARCH')
• The IMAP parser represents parenthesized groups as plain JS Arrays, not {type: 'LIST'} objects — the ESEARCH handler checks both forms for robustness
• Unknown ESEARCH keywords (e.g. MODSEQ from CONDSTORE) are silently skipped with correct stream alignment
• returnOptions strings are normalized to uppercase in both the command builder and fallback path

Tested against

• Dovecot with ESEARCH capability — 150k message mailbox
• Verified COUNT, ALL, MIN, MAX all return correct results
• PARTIAL handled gracefully when server doesn't advertise the capability